Suzy B Software 2/Suzy B Software CD-ROM 2 (1994).iso/bootup/boot_a2m/darklord/dckit.txt

Text File | 1995-05-02 | 41KB | 823 lines

The DarkLord Construction Kit

Manual for version 1.1

26th February 1994

1. Introduction

The DarkLord Construction Kit (hereafter just `DCK') is a utility for
creating the control files (the files with a .DKL extension) needed by
the DarkLord screen saver. It does not produce the optional external
modules used by DarkLord - you will have to code these yourself.
However, it does make the creation of the `DKL' file as painless as
possible.

Without a DKL file, DarkLord itself can't really do very much. All it
will do is blank the screen after 3 minutes without the user moving
the mouse or pressing a key. To use any of the inbuilt effects of
DarkLord, or to load and run a prewritten external module, you need to
load a file which controls the various parameters of the program.
These files have the extension "DKL".

2. System requirements

DCK will run on any Atari ST/TT/Falcon. As some of the dialog boxes
are quite large, many features are only available in screen widths of
640 pixels or more (which means that most functions are not available
in ST low resolution). Normally, you should use ST medium or high
resolution, or an 80-column mode on the Falcon or TT. The exception is
for colour editing: if you want to edit more than 4 colours on an ST,
you will need to switch to low resolution.

3. Installing and running DCK

3.1 Installation

Installing DCK is simple. Simply copy the files in the folder named
`DCKIT' to a floppy or a hard disk. The DKL files which you create
don't have to be stored here, they (and the external modules) can be
stored anywhere. Run DCK in the usual way from the desktop or a shell
program.

3.2 The program interface

The DCK menu consists of the following menu titles:

DC Kit   File      Edit      Options

Each title has a number of entries associated with it. Keyboard
shortcuts are provided for almost all menu entries and are shown on
the right hand side of the menu. A menu entry which has a series of
three dots after the name (e.g. Save As...) means that selecting this
entry will bring up a dialog box for further selections to be made.

Some menu selections and dialog boxes use popup menus. When you click
on such an option, a small menu will pop up which lists the available
choices in the same way as a conventional GEM menu. You can select any
option in the usual way, or click somewhere on the screen away from
the menu to cancel the choice. In these menus, the currently selected
option will be marked with a tick mark. You will usually find that
when the menu appears the mouse is over the currently selected
(ticked) option, unless the position of the mouse on the screen
doesn't permit this (e.g. it is too near one of the screen edges).

4. Using the DarkLord Construction Kit - a tutorial

Rather than a long description of the various operations which DCK can
undertake, it might be easier to show how it works by means of a
tutorial. A full description of its functions follows at the end of
this manual.


This tutorial assumes that you have installed DCK as described in
section 3 above, and you have run it so that you are now looking at a
blank screen with the Kit's menu bar at the top. If you have already
been experimenting with DCK, pull down the File menu and select `New'.
Click on `OK' when the alert box appears. This will restore DCK to its
default state, as it is when first run.

For this tutorial, we will create a simple DKL file which will cause
DarkLord to load and run an external module.

The first thing to do is to set some miscellaneous options, required
for the control of DarkLord. From the Edit menu, select
`Miscellaneous...'. A large dialog will appear.

The dialog box contains four boxes, containing different parameters
which may be set. At the top left is a box headed `Watch for
activity'. DarkLord works by watching for mouse movements and/or
keypresses. If it detects any activity, then it will reset its
internal timer so that the specified interval must elapse without any
further activity before the screen saver cuts in. If the screen saver
is already active, then the detection of activity will cause control
to be returned to the operating system.

This box allows you to decide which activities DarkLord will watch
for. By default, it watches for mouse movements (or button presses),
keypresses, and disk activity, and in general these are the best
options, so we will leave it like that for the moment. If you have a
modem attached, and you would prefer that the screen saver did not
activate while input/output through the modem port was happening, then
click on the `Modem' box to select it. You can do the same with the
`MIDI' box if you are using MIDI equipment.

At the bottom left of the dialog is a box which allows you to set the
time which must elapse without activity before the screen saver
activates. By default this is three minutes, but you can change this
to anything from 1 to 99 minutes (see the reference section for the
special case of a zero minute delay). Below the time display is a box
marked `Clear screen on entry'. If this box is selected, DarkLord will
clear the screen when it activates. The module we will use in this
tutorial requires the screen to be cleared,, so leave the box as it is
(selected ).

At the top right of the dialog is a box headed `Colour rotation'. If
an external module is to be loaded, this box is irrelevant and we can
leave it as it is. Finally, at the bottom right there is a box for two
special cases. Leave these in their default state (neither is
selected) for this tutorial.

Those are all of the options to be set, so click on `OK' to remove the
dialog box. Next we can change the colour palette if required. Choose
`Colour...' from the Edit menu and a series of boxes will be displayed
in the available screen colours. If you are running in monochrome,
only two boxes are shown; in ST low resolution, there will be 16. On
the TT or Falcon 256-colour modes, you will see only 16 colours, but
the remainder of the palette can be altered by using the box at the
bottom of the dialog to display the next block of 16 colours. If you
are running in Falcon True Colour mode, the palette display will not
be available.

At this point you can change any of the colours. Click on the box
filled with the colour to be changed. Its RGB (red, green, blue)
colour values will be shown in the boxes on top of the three sliders
to the right of the dialog. You can alter these colours by using the
sliders, in the same way as the Atari Control Panel. For this
tutorial, you can alter the colours to whatever you like. Do remember
though that the very first colour in the palette will be used as the
background colour, and for the module we will use here it is best set
to black.

At the top of the dialog is a button indicating how many colours will
be saved in the .DKL file. Leave this as it is for this tutorial. When
you have finished, click on `OK'. If you have changed the colour
palette, DCK will change it back to the palette it found when first
run. If you select the colour palette display a second time, it will
change back to your new, altered palette. This ensures that you can
alter the palette as much as you like and still have a readable screen
display for all other functions.

DarkLord also has the option to activate itself if the mouse is moved
into a particular area of the screen - the `activation hot spot'. You
can change the position of the hot spot by clicking on the `Hot
spot...' entry in the Edit menu. A small dialog box appears; the hot
spot itself can be in one of the four corners of the screen (or can be
disabled completely by selecting `None'). By default it is the top
right corner of the screen but this can be changed if you wish.

Now we can start on the module. In the Edit menu you will see that
four of the entries are greyed out (unavailable). This is because
these entries must be associated with a particular module. So, the
first thing to do is find the module. Choose the `Module filename'
entry. A small dialog will be shown, which in turn shows the module
file in the middle. At the moment, this will be blank because we
haven't chosen a module yet. Click on the button marked `Fsel...' and
the GEM file selector will appear. Use this to find the module with
the file name `GLOBES.DMO' Double-click on this file (or single click
and then click on OK in the file selector) to choose it. You will see
its name appear in the dialog box. Click on OK in the dialog, and you
will find that the other entries in the Module menu are now available.

Firstly, choose the `Author and title...' entry. This allows the
author of a module to enter his/her name here, along with the module's
title. In the two lines for the author, you can enter your name if you
wish (I don't mind if you claim authorship of this module!). In the
line for the title, you can enter any suitable title; try `Globes!'
for want of anything better.

Next, choose the `Module flags...' entry from the Module menu. This
will bring up a small popup menu with three entries, one for each of
three flags. This particular module only uses flag 1 (and it must be
flag 1) so click on `Flag 1' in the popup. A dialog box will appear
with 6 editable lines of text in it. At the moment all of these will
be empty.

Each flag may have up to 6 different states, but the important point
is that, depending on which state is currently selected, DarkLord will
pass a number to the loaded external module. The module reads this
number and alters its activities accordingly. In this case the flag
only has two different states. In the first line, type the words `Draw
spheres'. In the second line, type `Draw ellipses'. Now we can select
which of these is to be the default option when the DKL file is loaded
by DarkLord. If you click on the round button next to the first line,
it is these words which will be displayed in the box in DarkLord's
`Flags' dialog box, or you can click on the button associated with the
second line if you wish.

The module `GLOBES.DMO' only uses this one flag, which determines
whether the module will draw spheres or ellipses. Regardless of which
option you select as a default, you can change the selected option at
any time from DarkLord's control panel. Click on OK when you have
completed the flag setup.

Finally, choose the `Module variables...' entry from the Module menu.
These variables are more sophisticated than the flags, which simply
switch between up to 6 different but fixed states. The variables on
the other hand enable the user to adjust a number (between predefined
limits) from the DarkLord control panel. There are three such
variables available, and this module uses two of them.

These two variables govern the maximum and minimum sizes of the
spheres/ellipses which the module will draw. The module will choose a
random size for the sphere/ellipse which lies between the minimum and
maximum sizes the user has set.


For the first variable, enter the text `Minimum size' in the area
marked `Name'. You now have to enter the limits which the user can
choose between. For the area marked `Min' enter a value of 10; for the
area marked `Max' enter 40. You should now enter a starting value
which must lie between the minimum and maximum values you have set. If
you don't do this, DCK will automatically set a starting value midway
between the upper and lower limits.

For the second variable, enter the text `Maximum size' and the values
40 (for `Min') and 100 (for `Max'), plus a suitable starting value.

When this file is loaded into DarkLord, you will be able to adjust the
minimum and maximum sizes of the objects the module will draw; the
module will choose a value randomly between these two sizes. For
example, if you use DarkLord's control panel to set the minimum size
to 10 and the maximum size to 100, you will get a very wide range of
sizes; if you set both to 40, the objects will all have the same size.
Experiment with this and see how it works.

The file is now complete. To save it, select `Save as...' from the
File menu and save it with an appropriate name, e.g. GLOBES.DKL (make
sure it has the DKL extension). To test it, load it into the DarkLord
desk accessory (or run DarkLord as a program if it is not loaded as an
accessory) and click on `Activate' in the control panel. If DarkLord
is loaded as an accessory, there's no need to exit DCK before loading
and running your new .DKL file. Just save the file from DCK, call up
the accessory, and load the .DKL file.

Note: if you don't want to work through this tutorial, the file
GLOBES.DKL is supplied as part of the package. The source code for the
external module is also supplied.

5. Reference section

This section describes the various functions of DCK and the effect
that they have. They are listed by menu and by entry in the respective
menus. If a keyboard shortcut is present, it is given after the menu
entry name. Wherever possible, keyboard shortcuts follow the
guidelines recommended by Atari. A shortcut such as F1 represents a
function key.

5.1 Desk accessories

These are available as usual under the `DarkLord CK' menu. This menu
also contains an entry marked `About DarkLord CK'. If you click on
this a dialog box appears which gives you some copyright information,
the version number of the program (important if reporting bugs), and
the name of the loaded DKL file (if any) currently being edited.

5.2 The File menu

5.2.1 New (Control-N)

This option will clear out any existing .DKL file data and return the
program to the same state it was in when first run. Once selected,
data is lost irrecoverably so you are asked to confirm that you want
to do this (unless you have turned the warning off with the `Expert'
function).

5.2.2 Open (Control-O)

This loads a .DKL file from disk. It will overwrite any existing data
so you are asked to confirm the action (unless you have turned the
warning off). The file selector is displayed and you choose a file to
load in the usual way. If you try to load a file which is not a .DKL
file, you will be informed of this, but you will not lose any current
data.

5.2.3 Save (Shift-Control-S)

This will save a DKL file with its existing name, overwriting any file
with the same name already on disk. No warning is given before saving
the file. If you are creating a file which has not yet been named,
this menu entry will be disabled (unavailable). In that case, use the
`Save as...' menu entry. To see what name (if any) the file being
edited has, choose the `About DarkLord CK' entry from the desk
accessory menu.

5.2.4 Save as... (Control-S)

This saves a DKL file, but brings up the file selector first allowing
you to choose the name for the file, or cancel the save action. If you
choose the name of an existing file, no warning is given that the file
will be overwritten.

5.2.5 Import palette... (Control-C)

This will load a palette file saved with the `Save palette...'
function described below. It will replace any existing palette in
memory. The file selector is displayed and palette files have the
extension `DPA'. No warning is given before loading the palette. Note
that loading a palette only alters the current colour palette, but not
any other data in the DKL file being edited.

5.2.6 Export palette... (Control-X)

This option will first bring up the file selector then save the
current colour palette to disk. You should always specify the
extension `DPA' for DarkLord palette files. The number of colours
saved in the palette depends on the number selected in the Colour
Palette dialog box (see below). For example, if you have loaded a DKL
file containing only two colours, then only two colours will be saved,
even if you are in 16 colour mode. But if you are in 2 colour mode,
then choose to save 256 colours, then 256 colours will be saved even
though 254 of them may be black!

A more detailed description of how DCK uses colour palettes will be
found in the section on the Colour Palette Editor below.

5.2.7 Extract palette... (Control-V)

This allows you to extract the colour palette from an existing DKL
file on disk and copy it automatically into the file you are editing.
This is provided so that you can easily use palettes from prewritten
DKL files. If this facility was absent, then you would have to save
the current DKL file, load the one containing the palette you wanted,
save its palette, reload the original DKL file and load the new
palette back in. This command short-circuits this long winded method;
as with loading a palette file, only the colour palette data is
changed, everything else stays the same.

6. The Edit menu

6.1 Colour... (F1)

This entry brings up the Colour Palette editor. The editor has four
main components. In the middle and to the left of the dialog box are a
number of different coloured boxes, each representing a different
colour. One of these boxes is indicated by a surrounding border as the
colour currently being edited.

The number of boxes visible depends on the number of colours available
in the screen resolution you are currently in. In ST high resolution,
there are only 2; in medium resolution there are 4, while there are 16
in low resolution. In the 256-colour modes of the TT and Falcon, only
16 coloured boxes are present at any time but the extra colours can be
edited by using the colour group selector described below.

To the right of the colour boxes are three vertical sliders,
representing the three primary colours of red, green, and blue which
make up all colours. Each slider has a box at the top which shows the
current value of that primary colour, ranging from 0 to 1000. You can
alter the values of each primary colour by clicking on the box
contained within each slider with the mouse, holding down the button,
and moving the mouse to drag the slider. The colour value will be
updated when you release the button, and you will see the colour
change in the selected box. Finer control of each colour value is
provided by clicking on the up and down arrows above and below each
slider.

Note: in ST monochrome (high resolution) the colours cannot be
adjusted independently; one is always black and the other white. The
two colours can be swapped over, however. In all resolutions the
colour of the very first box (colour 0) is the background colour
DarkLord will use when it activates the screen saver.

Although each primary colour can theoretically be adjusted in the
range 0-1000, the ST hardware does not provide that degree of
adjustment. These values are used by GEM to set the colour, but each
is adjusted to fit the nearest colour available from the ST's
hardware. What this means is that, if for example you set a colour to
have RGB values of 172, 878, and 911 respectively, then when you come
to adjust that colour again you may find that the values have changed;
the actual colour is the same, but the values have been adjusted to
the nearest available equivalent.

At the bottom of the editor is the colour group selector, a small box
containing up and down arrows. This lets you select which group of 16
colours at a time you want to edit; of course, it can only be used in
screen modes which have more than 16 colours. Click on the arrows to
display a different group of 16 colours.

At the top of the dialog is a line of text reading `Save x colours in
palette', where `x' is a number. A small box contains the number,
which is the number of colours to be saved with the .DKL file. This
box is a popup menu; if you click on it, you can choose to save 0, 2,
4, 16, or 256 colours. All of these options are available regardless
of which screen mode you are currently in. Note that choosing to save
zero colours means that no colour palette data is saved as part of the
DKL file. Also, DCK will not allow you to save a palette (DPA) file
with no colours in it. Before you save a DKL or palette file, be quite
sure that the correct number of colours you want to save is selected
in the palette editor.

This may appear a little confusing: how can you save (say) 16 colours
if you are only in 4-colour mode? The reason is that DCK allows you to
load, but not edit, extended colour palettes. For example, suppose you
are in Falcon 256-colour mode, and you save all 256 colours as a
palette file. You cannot edit more than the first 16 colours in that
palette  with an ST, but you can still load and save this palette as
part of a DKL file so that an external module has the additional
colours available if it ever runs in a 256-colour mode.

Important note: the number of colours to save, as indicated in the
palette editor, is also saved as part of the DKL file you are editing.
If you are working in 16-colour mode, and you load a file which
contains only 4 colours, then resaving the DKL file will still only
save 4 colours. If you want to change this you must alter this number
manually to a higher (or lower) number as required. If you haven't
loaded an DKL file, or you have selected the `New' command from the
File menu, this number of colours which will be saved is however many
colours are available in the current screen resolution.

6.2 Miscellaneous... (F2)

Selecting this entry will bring up a large dialog containing four
boxes.

6.2.1 Monitoring computer activity.

6.2.1.1 Mouse & keyboard

The box at the top of the dialog allows you to set which activity of
the computer DarkLord will monitor. At its top there is a box which if
clicked on will display a popup menu. This determines whether DarkLord
watches mouse activity only, keyboard activity only, or both. DarkLord
will activate its screen-saving function if no activity of the mouse
and/or keyboard has occurred within the specified time period. (Mouse
activity includes mouse movements and button presses.) In addition,
once activated DarkLord will watch for activity and return control to
GEM if any activity occurs.

If keyboard monitoring is enabled, DarkLord will respond to presses of
the Shift, Alternate, or Control keys on their own (i.e. without the
need to use them in conjunction with some other key), and the cursor
keys, as well as the usual alphanumeric, function and special keys.

The default setting is to watch both the keyboard and the mouse, but
you can opt to only watch the mouse or only watch the keyboard. You
cannot opt to disable both mouse and keyboard monitoring, as once
DarkLord had activated you would have no way of regaining control of
the system!

It is best to leave DarkLord watching both mouse and keyboard unless
there is a good reason to switch one of these off. One such reason
would be if you are using a program which has a `dongle' plugged into
the mouse or joystick port. These dongles sometimes generate a
constant stream of mouse or keyboard interrupts which would mean that
DarkLord would never come into operation, since it would detect
apparently constant activity of the mouse or keyboard. If this
happens, try turning off mouse or keyboard monitoring.

Technical note: because of the way the mouse/keyboard interrupt system
works on the Atari machines, turning off mouse monitoring will force
DarkLord to use a different, less efficient way of monitoring the
keyboard, so that it will no longer respond to presses of the Shift,
Alternate, or Control keys on their own.

6.2.1.2 Monitoring the modem or midi ports

DarkLord can also monitor the modem and/or midi ports for input/output
activity. This is provided so that DarkLord will not cut in while
input or output through these ports is occurring, if you so wish. The
default state is not to monitor either port but you can choose to
monitor either or both by clicking on the respective buttons.

6.2.1.3 Monitoring disk activity

There is no simple, reliable method of watching for disk input/output
activity on the Atari machines. DarkLord will look for disk activity
at regular intervals and will not activate if the box labelled `Disk'
is selected. The default setting is to monitor disk activity. Most
disk activity is quite short, much shorter than the 1 minute which is
the minimum setting for the delay time before DarkLord activates.
However, prolonged periods of activity may occur when copying large
numbers of files, or backing up a hard disk.

For example, if you use Diamond Back from HiSoft to back up your hard
disk, you may find that DarkLord will activate partway through a
backup session. This is annoying because you then cannot see the
progress of the backup. Under these circumstances monitoring disk
activity can be useful in preventing DarkLord from activating during a
long backup session.

6.2.2 Delay time

The box at the lower left is where you set the time before DarkLord
activates. This is normally set at 3 minutes, but can range from 1 to
99 minutes. You can alter the time by editing the value in the usual
way.

What happens if you enter a time of zero minutes (or clear the time
line and leave it empty)? If DarkLord loads a file containing a zero
delay time when it is running as a desk accessory, it will ignore this
value and use the default 3 minute delay instead. When running as a
program, a zero delay is accepted as valid, so that DarkLord will
carry out its screen saving activity as soon as it is run and has
initialised.
Below the delay time is a box marked `Clear screen on activation'. If
this box is selected, DarkLord will clear the screen to the background
colour in the loaded palette (if there is one) or to the current
background colour if a palette wasn't loaded as part of a .DKL file.
If you don't want this to happen, click on this box to deselect it.
Some external modules look nicer if the screen is first cleared, while
for others the opposite is true.

6.2.3 Colour rotation

The box at the top right of this dialog allows you to set the colour
rotation time.

If an external module is not loaded, DarkLord will simply blank the
screen to the background colour in the loaded palette, if there is
one, or to the current background colour if there is no loaded
palette. The problem is that, if this colour is not black, this effect
might cause screen burn-in itself, rather negating the point of a
screen saver. Therefore, if no module is loaded, DarkLord can be
instructed to rotate the background colour through however many
colours are available in the current screen mode. The speed of
rotation is governed by the line labelled `Rotation time' which is the
time in seconds which must elapse before the colour is changed. This
is set to a minimum of 10 seconds, but can be longer.

If you really don't like this feature, you can turn it off by de-
selecting the colour rotation box, but take note of the warning in the
preceding paragraph.

Note: this feature is completely inoperative if an external module is
loaded, when it is assumed that the module will handle any necessary
colour cycling.

6.2.4 Additional options

The last box deals with two additional options.

6.2.4.1 Enable user message input

One use of an external module is to display a message on the screen
when the screen saver cuts in (for example, `Out to lunch' or `See you
in the pub at 5.30') or something similar. A module has to be
specifically written to display such messages, so the ability to input
a message is not normally present, and can only be enabled using DCK
if a module can handle such messages.

If this facility is enabled, a button entitled `Message...' will be
displayed in the main DarkLord control panel. This will allow the user
to enter a message of up to 3 lines.

6.2.4.2 Enable debug facility

If you are writing your own external modules DarkLord provides a
facility to stop execution just before your module is run, in order to
aid in debugging. To enable this facility, you must first enable
debugging using DCK by selecting the `Enable debug facility' box. If
you do this, a button will appear in the DarkLord's Toolbox which
reads `Debug'. The user can then select which will cause DarkLord to
stop with an `illegal' exception just before it executes a loaded
module. The separate file MODULES.TXT provides more information on how
to debug external modules.

This button is not present in DarkLord's control panel in normal use
since a user could select it without being aware of its potential,
which would cause a system crash when DarkLord tried to execute a
module. For this reason the Debug button is only provided if
specifically requested in DCK.

6.3 Hot spot... (F3)

A convenient way to activate DarkLord, especially when running as a
desk accessory, is to move the mouse pointer into an area of the
screen which is monitored by DarkLord. If it detects the entry of the
mouse into this area, DarkLord will activate.

This `hot spot' can be in any of the four corners of the screen,
although the top right corner is strongly recommended and is the
default setting. To alter the hot spot, select the `Hot spot' menu
entry (or press F3) and a small dialog box will be displayed. This in
turn shows a box representing the screen, with a smaller box at each
corner indicating the four possible positions of the hot spot. Click
on one of these to set the hot spot position.

If you don't want a hot spot at all, you can click on `None' to remove
it.

6.4 Module filename... (F4)

This is where you specify which external module is to be executed. You
are not obliged to have any external module at all if you don't want
one; all the other parameters referred to in preceding sections will
still work, and the colour rotation facility will be available if
there is no external module.

When you select this option, a small dialog is displayed. In the
middle is an editable line of text which is where the module file name
is shown. To select a module, click on the `Fsel...' button which will
bring up the file selector. You can then find the module, which should
always have a .DMO extension, with the selector. On return from the
selector the module name is shown in the box. Alternatively, if you
know the name of the module file, just type it into the text line. You
will see that the extension is fixed and is always .DMO. Note that the
location (directory) of the module is unimportant as DarkLord will
always load a module from the same location as the .DKL file
containing its name.

If you change your mind, and don't want a module after all, simply
clear the file name with the Backspace or Esc keys.

6.5 Module title... (F5)

This entry lets you enter some information about the name and author
of the external module to be loaded. The entry is not available until
you have selected a module to load.

This function brings up a dialog box with 2 lines of editable text at
the top, and one at the bottom. In the top 2 lines you should enter
the name of the module's author, plus any other details you wish (e-
mail address, for example). This information will be displayed in
DarkLord's information box.

The lower line is where you enter a suitable name for the module; this
will appear in all of DarkLord's dialog boxes.

Note that these entries are entirely optional and do not affect the
working of a module.

6.6 Module variables... (F6)

** Note: this section is only of interest to programmers writing
external modules. The module variables should not be altered except by
the module programmer. **

Many modules use parameters which can be adjusted according to the
users' preferences. The variables associated with an external module
allow the user to do this in a standard fashion. Up to three
independent variables may be used, but there is no need to use them if
they are not required. They should only be used where a parameter is
capable of alteration within a range of numbers. Where the choice is
between 2 or more fixed states, it is probably better to use the
module flags (see section 6.7 below).

To alter the variables, select this menu entry, which will display a
large dialog box. Within the box are three smaller boxes, one for each
variable. For each variable, you must set three numbers and the
variable must be given a name.

The first field in each variable is its name; this appears above the
slider bar in DarkLord's control panel. The name MUST be present for
the variable to be used. If the name field is left empty, DarkLord
will not display the slider bar for that variable, and if the name
fields of all three variables are empty the `Variables' icon on
DarkLord's main control panel will be disabled.

Each variable works by allowing the user to change its value within a
range which is set by the DKL file (and therefore ultimately by you,
the programmer of the module). The first number to enter is the
minimum value allowed for this variable; it can be any number,
including zero, but must be a positive number (you won't be able to
enter negative numbers). The second number is the maximum value for
that variable; again, any positive number is allowed, but it must be
greater than the minimum value. Finally, the initial value must be
entered; this is the value the variable will have when DarkLord first
loads the DKL file containing the variable. It must lie within the
range specified by the minimum and maximum values (but can be equal to
one of these limiting values).

Note that when a module is executed DarkLord will pass all three
values for each variable to the module.

When you click on OK (or press Return) to leave this dialog box, DCK
performs certain checks on the variable numbers you have entered.
These are:

    - any number with a blank field is given the value zero;

    - if the maximum value is smaller than the minimum value, it is
    set to the minimum value plus 1;

    - if the initial value falls outside the range, it is given a
    value halfway between the upper and lower limits.

DarkLord will warn you of the action it has taken if any of these
adjustments become necessary, unless you have turned on Expert mode
(see section 7.1 below).

Note that these checks will not be made unless the variable is
indicated as valid by the presence of some text in the name field for
that variable.

6.7 Module flags

** Note: this section is only of interest to programmers writing
external modules. The module flags should not be altered except by the
module programmer, except where specifically indicated. **

In addition to the numeric variables, a number assigned to up to three
switches, or flags, is passed to the module by DarkLord. Each flag can
have up to 6 different states, but only one state is the `active' one
which is passed to the module. The flag states are displayed via a
popup menu in DarkLord's control panel.

To set a flag, click on this menu entry. A small popup menu will
appear, allowing you to choose which flag you want to set. Click on
the appropriate flag and a dialog box will appear.

The box consists of 6 lines of editable text plus 6 round buttons, one
for each line. In each line you should enter whatever text is
appropriate for that particular state of this flag. You do not have to
use all 6 states if you don't need them, but you should start with
state 1 and move down the list in sequence; don't enter text for
states 1 and 2, miss a line, then enter something for state 4. This
will cause a blank line to appear in the popup in DarkLord.

When you have typed in all the required text, you can select which
state will be the default setting when DarkLord loads the DKL file.
Click on the appropriate round button to do this. (Incidentally, users
other than the module's programmer may change the default state if
required by using DCK to edit the flag settings, or by using the Save
facility from the DarkLord control panel.)

Note: DCK will not allow you to select a blank line as the initial
setting. If you do this, it will set the initial setting to state 1
when you exit the dialog. The very first state of each flag is a
special case (see below); if this is blank the flag won't be displayed
in DarkLord at all, so it doesn't matter if this is selected to be the
initial setting. DCK will warn you if it has made this change, unless
you turn off warnings by using Expert mode (see below).

When DarkLord loads the DKL file containing these flags, it shortens
the length of its popup menu by however many unused states there are
after the last used state. In other words, if you only use states 1,
2, and 3 of a particular flag, the popup DarkLord displays for that
flag will only contain 3 entries - not 3 lines of text plus 3 blank
lines. If you leave a blank state field sandwiched between state
fields with text in them however, this blank field will be shown. For
example, if you put text into states 1 and 2, nothing in 3, then text
in state 4, the popup will contain 4 entries, one of which will be
blank.

The final point to note about using these flags is that DarkLord will
not display a flag at all if the very first state field is empty; it
uses the contents of this field to determine if the flag is to be
used. Your use of the state fields should always commence with state 1
therefore, or the flag will not be available.

6.8 Resolutions... (F8)

Not all modules will be able to work in all screen resolutions. If you
are writing a module, at the least you should ensure that it can
function regardless of the actual screen size. DarkLord will pass the
screen width and height to a module when it is executed. Don't make
any assumptions about the screen size.

The only limiting factor (and avoid this as well, if possible) should
be the number of colours available. Obviously, if your module must
have 16 or more different colours on screen in order to function, it
shouldn't be used in 2-colour mode.

This option allows you to specify in which video modes the module will
work. By default, it is assumed that a module will work in any screen
mode, from 2-colour to True Colour. Selecting this entry brings up a
dialog box with 5 buttons in it. These represent video modes with
different numbers of bit planes, which correspond to the following
numbers of colours:

    Planes    Colours
      1           2
      2           4
      4          16
      8         256
     16       65536

True Colour mode on the Falcon does not use a bit plane structure for
screen memory, so a separate button is provided. (Note: the VDI
returns 16 bit planes for this mode on a Falcon, which is the value
DarkLord passes to a module; but DarkLord also sets a separate flag to
indicate whether or not the machine is in True Colour mode.)

All these buttons are initially selected, indicating that the module
will run in that video mode. If a module will not run in a particular
mode, click on the appropriate button to deselect it.

If DarkLord loads a module and finds from the DKL file that the module
won't run in the current screen mode, it will display a message
accordingly. The module will not execute in that mode, but all other
functions (including simple screen blanking) will work.

7. The Options menu

7.1 Expert mode (F9)

This is the only entry in this menu.

By default DCK will show warning messages when you try to carry out an
action which might lose data (such as loading a new file or quitting
the program) and if it detects errors in the entries for the module
variables and flags.

If you are sure you know what you're doing, you can turn off all these
warnings by selecting this option. Select it again to turn it back on.

8. Bug reports, etc.

I would be pleased to hear of any problems and bugs and particularly
ideas for future developments. Please note that this is the last
`free' version of DarkLord; future versions are likely to be
shareware. I may consider giving free registration to anyone who
writes an external module for DarkLord.

Finally, I would like to thank beta-testers, notably Ofir Gal, David
Billington, and Joe Connor for their comments and input.

I can be contacted by email on the CIX conference system
([e-mail]) or write to:

Steve Pedler, 12 Rudby Close, Gosforth, Newcastle upon Tyne, NE3 5JF,
England